Table of Contents

I recently upgraded some of my service hosts from Debian 12 to 13 and in that process, also made the switch from Docker, Inc.’s docker-ce container engine frontend to podman, since I’ve been previously using docker-ce frontend installed from external Docker, Inc. sources, which just never sat right with me (external repository dependencies, a for-profit company backing a crucial part of my infrastructure¹). Now that Debian 13 finally ships a relatively mature version of podman, I took that opportunity to make the switch. Here’s what I encountered and which fixes I had to apply.

Removing existing docker-compose stacks #

Before doing anything at all, I removed the running docker-compose stacks in their respective folders by running:

docker compose down

Uninstalling `docker-ce` #

Following the official Docker documentation (as you do), I took the listing of the mentioned packages from this page to heart and swiftly nuked all of them from my system:

apt remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Afterwards, I removed all unused packages, just in case:

apt autoremove

Installing `podman` #

For podman, I installed all the following packages:

apt install podman podman-docker docker-compose

This includes the following components:

podman: the actual container control frontend we want
podman-docker: a package for providing the docker command as an alias to podman.
docker-compose: the original docker-compose tool. The podman compose subcommand is provided as an alias to call this. I’ve chosen to keep using this implementation instead of podman-compose as the latter just doesn’t seem to be ready for my use cases yet.

Some fixes to get it running #

`docker.io` as an unqualified search registry #

To keep existing functionality in my stacks, which are using docker hub as their primary source (and as an unqualified registry), I had to modify the newly installed container registry configuration file located at /etc/containers/registries.conf and add docker.io as an unqualified search registry:

unqualified-search-registries = ["docker.io"]

`podman.socket` systemd service #

Afterwards, I tried starting up my stack again and was met with an API timeout error as the podman client tried to contact the service which was not yet running (strangely…even though the package ships with the unit enabled):

root@host-01:/stacks-of-cash# systemctl status podman.socket
○ podman.socket - Podman API Socket
     Loaded: loaded (/usr/lib/systemd/system/podman.socket; disabled; preset: enabled)
     Active: inactive (dead)
   Triggers: ● podman.service
       Docs: man:podman-system-service(1)
     Listen: /run/podman/podman.sock (Stream)

A quick fix was activating and enabling the systemd unit for the required socket:

systemctl enable --now podman.socket

External data directory #

Since I was using a shared directory for the docker cache, I migrated my existing storage config to podman:

root@host-01:/stacks-of-cash# cat /etc/docker/daemon.json
{
	"data-root": "/mnt/docker-cache"
}

For that, I created the file /etc/containers/storage.conf (docs) and added the following entries in it:

[storage]
driver = "overlay"
graphroot = "/mnt/docker-cache"
runroot = "/run/containers/storage"

Then, I cleaned out the cache directory (rm -rf /mnt/docker-cache/*) and restarted the host for good measure.

Container auto start #

After testing with my stacks again, I noticed that containers weren’t starting up again on a reboot even though having a policy of restart: always set in the docker-compose.yml file. A quick google search brought me on the right track: another systemd unit (podman-restart.service) had yet to be activated.

systemctl enable --now podman-restart

Disabling emulation warning #

Since the muscle memory for typing docker in the terminal has been deeply ingrained in my workflow, I won’t be changing the way I control my containers anytime soon. Podman keeps reminding you that you’re actually running podman though every time you call it from the docker alias, which was getting quickly on my nerves. They even tell you how to disable it:

touch /etc/containers/nodocker

Done! #

After applying all fixes, I restarted the host once more for good measure and was ready to go to production usage again. Starting up one of my stacks:

root@host-01:/stacks-of-cash# docker compose up -d
>>>> Executing external compose provider "/usr/libexec/docker/cli-plugins/docker-compose". Please see podman-compose(1) for how to disable this message. <<<<

[+] Running 2/2
 ✔ Network host-01_default   Created                                                                                             0.0s 
 ✔ Container boring-service   Started                                                                                             0.4s 
 ✔ Container watchtower       Started                                                                                             0.4s

Great success! ✨

stuff I found on google for this :) #

Yes, I know that I’m still using docker-compose, but I’m slowly phasing out that as well. One step at a time; podman-compose just isn’t mature enough for my use cases yet. ↩︎